El Mac 7/El Mac 7.iso/Actualizaciones/BBEdit 3.5.2 Update/HTML Tools Documentation/docs/Custom Markup Info.txt

Text File | 1995-11-22 | 15.5 KB | 429 lines | [TEXT/R*ch]

User's Markup Tool - part of the BBEdit HTML Tools package.
©1994 Lindsay Davies
email: [e-mail]


Status:                Semi-informal release pending feedback :-)
Last updated:        2/8/95



CUSTOM MARKUP ROUTINES
-------------------------------------------------------------------------

This tool will help those people who regularly have to process or edit HTML
documents. It allows you to define up to 20 'styles' that can be applied
to any part of your text.

(Background note: This tool started off with a rather more limited
scope in mind. It seems that in developing it, it has changed from being
a tool for storing simple markup styles to a simple macro package. So bear
in mind that macros weren't its original objective, and forgive its
rather clumsy design!).




Introduction:
-------------------------------------------------------------------------

To define your style, bring up the 'User Styles' tool, and you will see a
number of undefined buttons. To create a label and definition for your
style, simply click on a button and fill out the 'Label' and 'Definition'
fields (The definition field isn't yet labelled).

The best way to introduce the tool is with a worked-through example.
Suppose that we have a style for certain section headings that requires
marking up like this:

   <H2><I>My Heading</I></H2>
   <HR>

This would normally involve 4 operations (one for each of the
tags involved, and one for the return before the <HR> tag).

To define your own style to do this automatically, Make your definition
as follows:

   <H2><I>…</I></H2>\r<HR>

Working through this example we have the opening Heading tag,
the opening Italic tag, and then we have the important part, the
ellipsis. You type the ellipsis by using Option-; not by typing 3
periods. The ellipsis is the character that represents your current
selection. All text before the ellipsis goes before your selection, and
of course, everything after the ellipsis follows after the current
selection.

So after the ellipsis we have the closing Italic and Heading tags.
Following on from this is \r which represents a return character.
Finally we have the horizontal rule tag.

So if you select your text, eg

    My Heading

...and then apply this style to it, it will be marked up exactly as the
first example was, but in one operation.

If you have a number of headings to mark up, then you won't want to keep
going to the menu to do this. You can use the 'Repeat Macro' command
(command-short-option-T) to just redo the last operation.

OK, that's the basics. If you don't want to know any more, then save the
next bit till later! You may however wish to have a look at the examples
at the end of this document, which will give you an idea of the sorts of
things that you can do.



Intermediate Stuff:
-------------------------------------------------------------------------
In your style definition, you can put in certain placeholders. You have
already met the one for a return - \r. There are some others available to
help you with your creative impluses:

  Placeholder             Function
     \r                    Inserts return character
     \t                    Inserts tab character
     \c                    Inserts clipboard (eg whatever has been
                             most recently copied or cut.
     \b                    Inserts the contents of the buffer (more about this later)
     \…                    Inserts an ellipsis
     \\                    Inserts a slash
     \!                    Inserts an exclamation mark
     \"                    Inserts a quote
     \s                    Inserts the current selection
     \d                    Inserts the current date (short format)
     \D                    Inserts the current date (long format)


So far so simple (?). Now for some more stuff...



Slightly More Difficult Stuff:
-------------------------------------------------------------------------
I guess I'm lazy, but I thought I'd add a few extra things to help me
when I am marking up. So the next thing to learn about are the 'commands'
that you can insert into your style definition.

The commands simply allow you to manipulate and edit the current
selection in much the same way that you might do manually. Stringing a
series of commands together can allow you to perform quite complex tasks.

Again, we'll work through an example. The previous example relied
upon you selecting the text to be marked up. Much easier would be to
simply click in the text, and have your definition automatically select
the text for you.

So, referring back to the previous example, if we clicked in the middle
of the word 'heading', we might want to select the whole line before
applying the markup to it.

This is done using the command "!SL" (without the quotes). This reads as

        !    <--    The next 2 characters represent a command and parameter
        S     <--    'Select' command
        L    <--    This parameter means select the current line.

So the new definition would be:

   !SL<H2><I>...</I></H2>\r<HR>

Which reads as 'select the line, insert the '<H2><I>' bits before
the current selection, and insert  '</I></H2>' and a return character and
'<HR>' after the selection. (Hopefully you are still with me - there's more!).

However, a better way of doing it now that you've broken the ice with using
the commands is to stop using the ellipsis format, and try something like...

    !SL !IR"<H2><I>\s</I></H2>\r<HR>"
        ****       **               *

This reads pretty well as before, but the new bits (marked with an *) are..

    !IR"xxx"        Insert the following string, replacing the current selection.
    \s                places the current selection into the specified string.




List of Commands:

Command            Function
=======         ========
Selecting
    !SW            select the word that the insertion point is in
    !SL            select the line that the insertion point is in
    !SP            select the paragraph that the insertion point is in
    !SD            select the whole document.
    !SC            select all text and tags of a Container.
    !ST            select all Text within a container.


Copying
    !CC            copy the current selection to the clipboard
    !CB            copy the current selection to the Buffer.
    !CA            append the current selection to the clipboard
    !CT"xyz"    append the text 'xyz' to the clipboard (all the placeholders
                mentioned above can be used in this string).
    !CZ            clear the clipboard

Extending
    !EF"xyz"    extends the selection forwards to start of string "xyz"
    !E^            extend to start of line
    !E$            extend to end of line
    !E#"nnn"    extend selection by nnn characters. Value can be positive or negative

Inserting
    !IS"xyz"    insert text "xyz" at start of selection
    !IE"xyz"    insert text "xyz" at end of selection
    !IR"xyz"    insert "xyz" Replacing the selection

Finding
    !FN"abc"    find next occurrence of "abc" where "abc" can include the
                simple wildcards...
                '.'     matches any character
                '#'     matches any numeric character

    !FA"abc"    same as above, but will find all matches of "abc" in the
                document, and will invoke subsequent commands in the segment for all found
                occurrences.

                It will probably be useful to quickly explain the logic of this command.
                Effectively it works as...

                    repeat while "abc" is found
                        ...segment commands
                    end repeat

                If the search string isn't found, then any following commands in the
                segment will be skipped, and control will pass to the next segment.
                (Information about segments can be found later in this document.)

    !FS"xyz"    extends the selection forwards to start of string "xyz"


Place Insertion Point
    !@E            insertion point at end of selection
    !@S            insertion point at start of selection
    !@T            insertion point at top of document
    !@B            insertion point at bottom of document
    !@L            insertion point at next line
    !@P            insertion point at next paragraph
    !@^            insertion point at start of line
    !@$            insertion point at end of line

Case
    !KR            raise the case of the selection
    !KL            lower the case of the selection
    !KT            make all HTML tags upper case
    !KW            capitalize words.

Deleting
    !DS            delete the current selection
    !DX            delete current selection + surrounding space
    !DC            delete the clipboard

Misc
    !BP            Beep - useful in some cases when you are debugging a macro.
    !§k            Switch searching case sensitivity ON
    !§K            Switch searching case sensitivity OFF (Default)

Note that you can use Command-. to exit from any series of commands
you may be using.

*    Commands may have a single space between them to aid legibility.

*    The sequence of commands is limited to 255 characters in length.

A good example of using the commands is having a list of delegate names
for a conference. I want to have a main document with all the names, but
have links from the names to vanity pages for each of them. In addition,
I would like the names to be anchors. The names of the vanity pages are
all in the format surname.html in a directory called 'vanity', and using
the surname for the anchor name. eg:

Before:                After:

Joe Bloggs            <A NAME="Bloggs" HREF="/vanity/Bloggs.html">Joe Bloggs</A>
University of X        University of X
email: user@host    email: user@host


This would normally require a fair bit of mouse and keyboard work to do,
especially for a ist of 30 or so delegates. Better still would be to
create a style definition that would do it all for me. eg:

    !SW!CC!SL!IS"<A NAME=\"\c\" HREF=\"/vanity/\c.html\">"!IE"</A>"

Assuming that I have clicked anywhere in the surname (ie 'Bloggs'),
this definition reads as:

    !SW                    Select the Word (ie 'Bloggs')
    !CC                    Copy the selection
    !SL                    Select the Line.
    !IS"<A NAME=\"        insert this text before the selection (note '\"' is
                        required to enter a quote.)
    \c                    insert the clipboard (ie 'Bloggs)
    \" HREF=\"/vanity/    insert this text
    \c                    again, insert the clipbaord
    .html\">"            insert this text
    !IE"</A>"            and insert this text after the selection to finish off.


So, it doesn't look pretty, but it can be quite useful. If you want
anything more powerful, then you really need to get stuck into GREP or
PERL.

To recognise that you sometimes want to follow one style with
another, you can tell your definition which definition to use next.

Using the above example, I could have the definition just described to
mark up the name. I might then wish to have another definition to mark up
the email address. By adding !N2 in front of the first definition, the
next time the tool is used, definition 2 will be the default. (and if
_that_ definition includes a !N1, then repeated use of the tool will
cycle through these definitions 1 and 2.)


Obfuscation time...
-------------------------------------------------------------------------

There will be occasions when you want to perform a series of tasks. You
could allocate them all to different macros, but if they are all meant to
work together, this would be a waste of space.

You can therefore string together seqences of commands into 'segments'
within a definition. To delineate a segment, type a bullet (option-8).
You will see that the next segment will start on a new line, and be prefixed
by a bullet.

A simple example of this in use would be the situation where you wanted
to compile a list of all anchors in your document. The list will be
compiled on the clipboard, so the first thing you would need to do is to
clear it of any current text.

You will then want to find all anchors, so search for all text starting
with "<A " and ending with "</A>". If it is found, it will be selected,
and we want to append the selection and a return (so that all anchors
start on a new line) to the clipboard. You then need to move the
insertion point to the end of the selection so that the next iteration
won't simply select the same part again. Just to illustrate the point
further, when this second sequence has finished, we want to beep to
signify that we have come to the end.

The macro itself...

        !DC
        •!FA"<A .*</A>" !CT"\s\r"!@E
        •!BP

Note that there are three segments here - the first one that deletes the
clipboard only wants to be performed once. The newline and bullet
delineate the second segment, which iterates through the document
finding and appending the data to the clipboard. Only when this has
complete will the third segment be invoked, and the machine will beep.

Note the use of !@E to move the insertion point to the end of the selection.
Without this, the Find command will start searching again from the start of
the current selection, and will of course immediately find itself again!


Examples
-------------------------------------------------------------------------

Well, that's probably clear as mud, so here are some examples:


-------------------------------------------------------------------------
•  To embolden a word (just click anywhere in the word you want to
   embolden)

    !SW !IS"<B>" !IE"</B>"        Select the word, insert <B> at the start of the
                                selection, insert </B> at the end of the selection.

alternatively...

    !SW !IR"<B>\s</B>"            Select word, insert string which includes the current
                                selection between the tags.

-------------------------------------------------------------------------
•  To embolden a line:

    !SL !IS"<B>" !IE"</B>"        Exactly the same, but we use !SL instead of !SW.

-------------------------------------------------------------------------
•  To add paragraph tags to a paragraph:

    !SP !IR"<P>\s</P>"            Select paragraph, insert <P> container around selection.

-------------------------------------------------------------------------
•  To make a word into a named anchor:

    !SW !CC !IS"<A NAME="\c">" !IE"</A>"

    Select the word, copy it, insert the tag, inserting the clipboard between the quotes,
    and inserting the closing tag at the end of the selection.

-------------------------------------------------------------------------
•  To remove the current tags from around some text:

    !ST !CC !SC !IR"\c"        Select text up to tags, copy it, select containing tags
                            as     well, insert replacing the selection with what was
                            just copied.

-------------------------------------------------------------------------
•  To mark up glossary items (which are on consecutive lines):

        !SL !IS"<DT>" !FN"\r" !@E !IS"<DD>"

        Select line, Insert "<DT>" at the start of the selection, Find the next
        return character, move the insertion point after it, insert "<DD>" at
        the insertion point.

-------------------------------------------------------------------------
•  Copy all lines containing "BBEdit" to the clipboard

        !CZ                                    Clear the clipboard
        •!FA"BBEdit" !SL !CT"\s\r"            Find all occurrences of "BBEdit",
                                            Select the line, Copy-append Text containing
                                            the current selection and a carriage return.

-------------------------------------------------------------------------
•  Copy all lines containing "BBEdit", case significant, to the
clipboard

        !CZ!§k                                Clear the clipboard, set case switch ON
        •!FA"BBEdit" !SL !CT"\s\r" !@E        Find all occurrences of "BBEdit",
                                            Select the line, Copy-append Text containing
                                            the current selection and a carriage return.
                                            Then move cursor to end of found text ready
                                            for next iteration.

-------------------------------------------------------------------------
•  Compile and Insert a list of all the headings in a document

        !CZ!@T
        •!FN"<MENU>"!@S!FS"/MENU>"!FS"\r"!DS
        •!FA"<H#>"!@E!ST!CB!CT"<LI>\t<A HREF=\"#\b\">\b</A>\r"
        •!@T!FN"</H1>"!@E!IS"\r<MENU>\r\c</MENU>"!B3


-------------------------------------------------------------------------
•  To change the title of your document to word capitalization

        !@T !FN"<TITLE>" !ES"</TITLE>" !KW    Move insertion point to the top of the doc.
                                            Find next occurrence of <TITLE>. Extend
                                            selection to "</TITLE>", change case of
                                            selection to Word Capitalization.



(Last updated: 2/8/95)


Lindsay Davies,
email:    [e-mail]